feat(json-schema): resolve standalone JSON Schema 2020-12 documents - #4307

…erge)

Install @swagger-api/apidom-reference and
@swagger-api/apidom-ns-json-schema-2020-12 from tarballs packed from the
ApiDOM branch feat/json-schema-2020-12/phase-3 at commit 11951862a, which
adds the json-schema-2020-12 resolve and dereference strategies and exports
keyMap and getNodeType from the namespace. The tarballs live in
../upstream-tarballs; "$" overrides make nested copies use them.

Drop this commit once ApiDOM releases the branch, and bump every
@swagger-api/apidom-* package to that release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Add the json-schema-2020-12-apidom resolve strategy for documents whose root
$schema is https://json-schema.org/draft/2020-12/schema (an empty fragment
normalised) and which have no openapi or swagger field. Any other $schema
keeps the generic strategy. The strategy resolves over apidom-reference's
json-schema-2020-12 strategies, so $refs resolve against $id base URIs,
$anchor and $dynamicAnchor plain names and external documents as in
OpenAPI 3.1 Schema Objects; every $dynamicRef is left in place.

The json-schema-2020-12-swagger-client dereference strategy carries over the
OpenAPI 3.1 Schema Object handling (cycles, $$ref meta patches, collected
errors), merges allOf unless mode is strict and applies modelPropertyMacro,
so a schema resolves the same standalone and inside an OpenAPI 3.1
document. A $ref in the document root keeps its replacement as the parse
result. The JSON and YAML parsers detect a document by its parsed root and
are used only by this strategy; the OpenAPI parser lists are unchanged.

Register the strategy ahead of generic in Swagger.resolve and
Swagger.resolveSubtree, and export the parsers and the dereference strategy
in Swagger.apidom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Record the decisions the 2020-12 work answered (cross-dialect references,
unreleased upstream, content-detecting parsers, $ref to $dynamicAnchor) in
design-and-delivery.md, and in strategy-design.md refract with the
namespace's refract (apidom-ns-arazzo-1 reassigns JSONSchemaElement.refract)
and keep the result class on a dereferenced root.

FOLLOW-UPS: keyMap/getNodeType are exported on the unreleased ApiDOM
branch; new item for apidom-reference's uri selector, which resolves
candidate $id chains against the $ref target instead of the document's
base URI (OpenAPI 3.1 and 3.2 alike).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The dereference lineage held only the pathDiscriminator fragment, so a $ref
from the fragment to one of its ancestors was not a cycle: "$ref": "#" in a
recursive schema overflowed the stack when Swagger UI resolved
['properties'] or ['properties', 'children'] through resolveSubtree, and
['properties', 'children', 'items'] returned null. Seed the lineage with
the document root and every element along the pathDiscriminator, so such a
$ref resolves to an absolute $ref, as cycles do everywhere else.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

A document is standalone JSON Schema only when its root has the 2020-12
$schema and none of the API description fields openapi, swagger, asyncapi
and arazzo. AsyncAPI and Arazzo documents may declare a root $schema; they
keep the generic strategy they had, which regression tests check by
comparing with a generic-only resolve. The parsers detect through the same
predicate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

apidom-reference's $anchor selector searches embedded $id resources too and
takes the first match, so "#tag" can select the embedded resource's schema
instead of the referencing resource's (JSON Schema Core 8.2.2). OpenAPI 3.1
Schema Objects behave the same. Pin it with a test.failing fixture that
starts failing once ApiDOM stops the search at nested $ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

State the matching rule as no openapi, swagger, asyncapi or arazzo field
(D18) wherever it appears, record D18 and D19 in design-and-delivery.md,
require the pathDiscriminator lineage in strategy-design.md, and in
FOLLOW-UPS put 2.3 after 2.2 and add 2.4 for apidom-reference's $anchor
selector, which searches embedded schema resources.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot review of PR #4307 found that the circular replace return skips
indirections.pop() and that the resolve strategy cache reuses a graph
that dereferencing mutates. Both patterns come from the OpenAPI 3.1
strategy, so they are recorded as follow-ups for both.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>